Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Keccak1600_Squeeze/Absorb Layer (rename) #2097

Merged
merged 3 commits into from
Jan 7, 2025

Conversation

manastasova
Copy link
Contributor

Issues:

Resolves Keccak1600_ Layer creation, part of #CryptoAlg-2810

Description of changes:

  • Rename Absorb and Squeeze functions since they are Keccak-specific.
  • Remove of redefinition of |SHAKExxx_BLOCKSIZE| as |SHAKExxx_RATE|.

This PR introduces the lowest API layer for SHA3 and SHAKE new API design:

  • Introduce new Keccak1600 API layer.
    • Keccak1600 layer implements KeccakF1600 Absorb and Squeeze functions; Keccak1600 layer does not manage internal input/output buffers.
  • Later FIPS202, SHA3 and SHAKE layers will be introduced on the top Keccak1600 APIs.

Call-outs:

Remove OPENSSL_EXPORT from some SHA3/SHAKE functions.

Testing:

./crypto/crypto_test --gtest_filter="KeccakInternalTest.*"
./crypto/crypto_test --gtest_filter="SHA3Test.*"
./crypto/crypto_test --gtest_filter="SHAKETest.*"

./crypto/crypto_test --gtest_filter="All/PerKEMTest.*"
./crypto/crypto_test --gtest_filter="All/PQDSAParameterTest.*"

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license and the ISC license.

Clean redefinition of SHAKE blocksize/rate macros; Update their use inside MLKEM and MLDSA.
@manastasova manastasova requested a review from a team as a code owner January 6, 2025 23:11
@codecov-commenter
Copy link

codecov-commenter commented Jan 6, 2025

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 78.75%. Comparing base (697acc6) to head (872d368).

Additional details and impacted files
@@           Coverage Diff           @@
##             main    #2097   +/-   ##
=======================================
  Coverage   78.74%   78.75%           
=======================================
  Files         598      598           
  Lines      103656   103656           
  Branches    14720    14720           
=======================================
+ Hits        81622    81632   +10     
+ Misses      21382    21373    -9     
+ Partials      652      651    -1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

@jakemas jakemas self-requested a review January 6, 2025 23:54
@@ -64,11 +64,9 @@ extern "C" {
// SHAKE constants, from NIST FIPS202.
// https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf
#define SHAKE_PAD_CHAR 0x1F
#define SHAKE128_BLOCKSIZE (KECCAK1600_WIDTH - 128 * 2) / 8
#define SHAKE256_BLOCKSIZE (KECCAK1600_WIDTH - 256 * 2) / 8
#define SHAKE128_RATE 168
Copy link
Contributor

@jakemas jakemas Jan 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for cleaning these (SHAKE128/256_RATE) up!

Fix alignment

Co-authored-by: Jake Massimo <[email protected]>
@andrewhop andrewhop merged commit edeb62f into aws:main Jan 7, 2025
124 of 125 checks passed
justsmth added a commit that referenced this pull request Feb 5, 2025
### Issues:
Resolves #CryptoAlg-2810

### Description of changes: 
AWS-LC supports SHA3 and SHAKE algorithms though low level SHA3_Init,
SHA3_Update, SHA3_Final and SHAKE_init, SHAKE_Final APIs. Currently,
there are two issues with the implementation and usage of SHA3 and
SHAKE:
- There is no support for SHAKE_Update function. SHAKE is implemented by
calling SHAKE_Init, SHA3_Update and SHAKE_Final.
- SHAKE_Final allows multiple consecutive calls to enable incremental
XOF output generation.

This PR addresses both of them as follows:
- Introduce new API layers - FIPS202, SHA3 and SHAKE. 
- _Keccak1600_ layer (#2097)
implements KeccakF1600 Absorb and Squeeze functions; Keccak1600 layer
does _not_ manage internal input/output buffers.
- _FIPS202_ layer implements Reset, Init, Update, and Finalize
functionalities; FIPS202 layer manages the internal input/output
buffers, allowing incremental requests (not necessarily multiple of
block size) to Update (Absorb) and Squeeze for input/output processing.
(Other functionalities, such as zero-ing of bitstate, block size checks,
etc. are also handled by FIPS202 API layer).
- _FIPS202_ layer implements all common behavior between SHA3 and SHAKE
algorithms.
- _FIPS202_ layer checks/updates the |ctx->state| flag when handling a
common behavior between SHA3 and SHAKE algorithms. |ctx->state| is
updated in the higher level SHA3_ SHAKE_ API layer when the behavior of
both algorithms diverges (SHAKE _can_ allow incremental squeezes).
- _SHA3_ layer implements Init, Update, and Final functionalities; SHA3
layer only implements SHA3 algorithm, thus, offers a single-call
SHA3_Final function. SHA3_Final will update internal |ctx->state| flag
to prevent any sequential calls.
- _SHAKE_ layer implements XOF SHAKE algorithm, therefore, offers Init,
Absorb, Squeeze, and Final functionalities;
- _SHAKE_ layer implements Init, and Absorb, Squeeze with incremental
call support for absorb (byte-wise) and squeeze (block-wise).
- _SHAKE_ layer implements a single-call SHAKE_Final function that
generates an arbitrary length output and finalizes SHAKE. Incremental
XOF output generation is handled by |SHAKE_Squeeze|. |SHAKE_Squeeze| can
be called multiple times. SHAKE_Final should be called only once.

- KECCAK600_CTX struct updates:
   - Remove |padded| field
   - Introduce |state| field
- |state| can be |KECCAK1600_STATE_ABSORB|, |KECCAK1600_STATE_SQUEEZE|,
|KECCAK1600_STATE_FINAL|
- |KECCAK1600_STATE_ABSORB| - allows incremental absorbs until the state
is changed
- |KECCAK1600_STATE_SQUEEZE| - allows incremental squeezes for
|SHAKE_Squeeze|
- |KECCAK1600_STATE_Final| - prevents from incremental squeezes via
|SHAKE_Final| and prevents from consecutive calls to |SHA3_Final| (Final
functions are single-shot functions).

SHA3 vs SHAKE algorithms (APIs usage):
>- SHA3 digest generation: SHA3_Init; SHA3_Update; SHA3_Final;
>- SHAKE (single-shot-output) output generation: SHAKE_Init;
SHAKE_Absorb; SHAKE_Final;
>- SHAKE (incremental) output generation: SHAKE_Init; SHAKE_Absorb;
SHAKE_Squeeze<sup>+</sup>;

### Call-outs:
Service indicator is updated: 
- Inside SHA3 and SHAKE single shot APIs (as previously in AWS-LC);
- Inside SHA3_Final (as previously in AWS-LC);
- Inside SHAKE_Final (Single-Shot XOF Final output generation as
previously in AWS-LC);
- Inside SHAKE_Squeeze (Streaming XOF Squeezes output generation updates
the service indicator after each extendable output update);

All other algorithms that use SHA3/SHAKE APIs are updated:
- ML-KEM (SHA3/SHAKE calls will be inlined later)
- ML-DSA (SHAKE_Squeeze (incremental XOF output functionality) inside
ML-DSA is never invoked with the KAT test vectors and gtests)
### Testing:
_./crypto/crypto_test --gtest_filter="KeccakInternalTest.*"_
_./crypto/crypto_test --gtest_filter="SHA3Test.*"_
_./crypto/crypto_test --gtest_filter="SHAKETest.*"_

_./crypto/crypto_test --gtest_filter="All/PerKEMTest.*"_
_./crypto/crypto_test --gtest_filter="All/PQDSAParameterTest.*"_

By submitting this pull request, I confirm that my contribution is made
under the terms of the Apache 2.0 license and the ISC license.

---------

Co-authored-by: Jake Massimo <[email protected]>
Co-authored-by: Will Childs-Klein <[email protected]>
Co-authored-by: Justin W Smith <[email protected]>
Co-authored-by: Shubham Mittal <[email protected]>
Co-authored-by: Samuel Chiang <[email protected]>
Co-authored-by: David Benjamin <[email protected]>
Co-authored-by: Theo Buehler <[email protected]>
Co-authored-by: Adam Langley <[email protected]>
Co-authored-by: Brian Ledger <[email protected]>
Co-authored-by: Nick Harper <[email protected]>
Co-authored-by: Andrew Hopkins <[email protected]>
Co-authored-by: torben-hansen <[email protected]>
Co-authored-by: Sean McGrail <[email protected]>
Co-authored-by: olivergillespie <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants